C++

Reference

<locale>

header

<locale>

Localization library
A locale is a set of features that are culture-specific, which can be used by programs to be more portable internationally.

In C++, locales are represented by an object of the locale class. Each of these locale objects contains all the information needed to use a set of culture-dependent features. But locale objects do not contain the features directly themselves as member functions: instead, a locale object contains information about which facet objects it selects, and is each one of these facet objects that implements specific features as member functions. This allows for features that are common to several locales to be shared by using the same facet objects, and makes them extensible, allowing custom facets to be added to locale objects.

Facets are divided into six standard categories:

categoryfacetmember functions
collatecollatecompare, hash, transform
ctypectypeis, narrow, scan_is, scan_not, tolower, toupper, widen
codecvtalways_noconv, encoding, in, length, max_length, out, unshift
monetarymoneypunctcurr_symbol, decimal_point, frac_digits, grouping, negative_sign, neg_format, positive_sign, pos_format, thousands_sep
money_getget
money_putput
numericnumpunctdecimal_point, falsename, grouping, thousands_sep, truename
num_getget
num_putput
timetime_getdate_order, get_date, get_monthname, get_time, get_weekday, get_year (and get, since C++11)
time_putput
messagesmessagesclose, get, open

Locale objects can be constructed entirely from a name, taking all the characteristics of that named locale, or they can mix facet categories of different locales (see class locale constructor for more info).

Thus, the core of the localization functionality in C++ is implemented in the different facets. Facets are objects. These objects are managed automatically by the locale engine, therefore facet objects are generally neither constructed nor copied locally in a program (in fact a program is prevented to do so by their protected destructors). The most general way of accessing a particular feature of a facet associated with a locale is with the function use_facet:

1
2
3
4
5
6
 
// using facet member directly:
myvar = use_facet < numpunct<char> > (mylocale).decimal_point();

// alias facet:
const numpunct<char>& myfacet = use_facet < numpunct<char> > (mylocale);
myvar = myfacet.decimal_point();

Every facet:
  • is derived from class locale::facet (or from any class derived from it, like another facet).
  • define a static member called id of type locale::id with a specific value.
A program may define its own facets to be added to a locale by fulfilling the above requirements.

All facet constructors include as second parameter (called refs in this reference) that defines whether the class deallocation is delegated to the locale engine, and hence it is automatically deleted when the last locale object where it is present is destroyed, or whether the program is in charge of its deletion at some point.

Some facet have an equivalent but ending with "_byname". These facet types are used by the localization engine to construct the appropriate facet objects when a named locale object is constructed.

All the standard facets are designed with public members that call virtual protected members with the same name, but preceded with "do_". The implementation of the operation itself lies in the virtual protected member function (so that derived class can easily overwrite it), while the non-virtual public function may implement platform-specific functionality not related to the operation itself, but necessary to allow the feature to work properly on the system.

All library implementations provide at least all the facets by default for the char and wchar_t types as template parameters for the facet's character type.
All library implementations provide at least all the facets by default for the char and wchar_t types as template parameters for the facet's character type. Additionally, the codecvt facet is also required to support char16_t and char32_t.

Functions

Facet management:
use_facet
Access facet of locale (function template)
has_facet
Check if locale has facet (function template)

Convenience interfaces (template versions of the cctype functions):
isspace
Check if character is a white-space (function)
isprint
Check if character is printable (function)
iscntrl
Check if character is a control character (function)
isupper
Check if character is uppercase letter (function)
islower
Check if character is lowercase letter (function)
isalpha
Check if character is alphabetic (function)
isdigit
Check if character is decimal digit (function)
ispunct
Check if character is a punctuation character (function)
isxdigit
Check if character is hexadecimal digit (function)
isalnum
Check if character is alphanumeric (function)
isgraph
Check if character has graphical representation (function)
isblank
Check if character is blank (function)

Classes

locale
Locale class (class)

Standard facets:
ctype
Character type facet (class template)
ctype_byname
Character type facet (class template)
codecvt
Convert codeset facet (class template)
codecvt_byname
Convert codeset facet (class template)
num_get
Facet to parse numeric values (class template)
num_put
Facet to format numeric values (class template)
numpunct
Numeric punctuation facet (class template)
numpunct_byname
Numeric puntuation facet (class template)
collate
Facet to compare and hash strings (class template)
collate_byname
Facet to compare and hash strings (class template)
time_get
Facet to parse dates and times (class template)
time_get_byname
Facet to parse dates and times (class template)
time_put
Facet to format dates and times (class template)
time_put_byname
Facet to format dates and times (class template)
money_get
Facet to parse monetary expressions (class template)
money_put
Facet to format monetary expressions (class template)
moneypunct
Monetary punctuation facet (class template)
moneypunct_byname
Monetary punctuation facet (class template)
messages
Facet to access message catalogs (class template)
messages_byname
Facet to access message catalogs (class template)

Base classes for standard facets (defining member types):
ctype_base
Base class for ctype (class)
codecvt_base
Base class for codecvt (class)
time_base
Base class for time_get (class)
money_base
Base class for moneypunct (class)